---
title: Announcing v0.6.0 with Versioned Migration Authoring
authors: a8m
tags: [atlas, migrations, versioned]
image: https://blog.ariga.io/uploads/images/posts/v0.6.0/atlas-migrate-diff.png
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import InstallationInstructions from '../../md/components/_installation_instructions.mdx'

With the release of [v0.6.0](https://github.com/ariga/atlas/releases/tag/v0.6.0), we are
happy to announce official support for a style of workflow for managing changes to database
schemas that we have been experimenting with in the past months: _Versioned Migration Authoring_.

### TL;DR

* Atlas supports a declarative workflow (similar to Terraform) where users provide the 
 desired database schema in a simple [data definition language](https://atlasgo.io/atlas-schema/sql-resources)
 and Atlas calculates a plan to get a target database to that state. This workflow
 is supported by the [`schema apply`](https://atlasgo.io/declarative/apply) command.
* Many teams prefer a more imperative approach where each change to the database schema 
 is checked-in to source control and reviewed during code-review. This type of workflow
 is commonly called _versioned migrations_ (or _change based migrations_) and is supported by many established tools such
 as [Flyway](https://flyway.org) and [Liquibase](https://liquibase.org).
* The downside of the versioned migration approach is, of course, that it puts the burden of 
 planning the migration on developers. As part of the Atlas project we advocate for 
a third combined approach that we call "Versioned Migration Authoring". 
* Versioned Migration Authoring is an attempt to combine the simplicity and 
 expressiveness of the declarative approach with the control and explicitness of versioned migrations.
* To use Versioned Migration Authoring today, use the `atlas migrate diff` command. See
  the [Getting Started](#getting-started) section below for instructions. 

### Declarative Migrations

The declarative approach has become increasingly popular with engineers nowadays because it embodies
a convenient separation of concerns between application and infrastructure engineers.
Application engineers describe _what_ (the desired state) they need to happen, and
infrastructure engineers build tools that plan and execute ways to get to that state (_how_).
This division of labor allows for great efficiencies as it abstracts away the complicated
inner workings of infrastructure behind a simple, easy to understand API for the application
developers and allows for specialization and development of expertise to pay off for the
infra people.

With declarative migrations, the desired state of the database schema is given
as input to the migration engine, which plans and executes a set of actions to
change the database to its desired state.

For example, suppose your application uses a small SQLite database to store its data.
In this database, you have a `users` table with this structure:
```hcl
schema "main" {}

table "users" {
  schema = schema.main
  column "id" {
    type = int
  }
  column "greeting" {
    type = text
  }
}
```

Now, suppose that you want to add a default value of `"shalom"` to the `greeting`
column. Many developers are not aware that it isn't possible to modify a column's
default value in an existing table in SQLite. Instead, the common practice is to
create a new table, copy the existing rows into the new table and drop the old one
after. Using the declarative approach, developers can change the default value for
the `greeting` column:

```hcl {10}
schema "main" {}

table "users" {
  schema = schema.main
  column "id" {
    type = int
  }
  column "greeting" {
    type = text
    default = "shalom"
  }
}
```
And have Atlas's engine devise a plan similar to this:
```sql
-- Planned Changes:
-- Create "new_users" table
CREATE TABLE `new_users` (`id` int NOT NULL, `greeting` text NOT NULL DEFAULT 'shalom')
-- Copy rows from old table "users" to new temporary table "new_users"
INSERT INTO `new_users` (`id`, `greeting`) SELECT `id`, IFNULL(`greeting`, 'shalom') AS `greeting` FROM `users`
-- Drop "users" table after copying rows
DROP TABLE `users`
-- Rename temporary table "new_users" to "users"
ALTER TABLE `new_users` RENAME TO `users`
```

### Versioned Migrations

As the database is one of the most critical components in any system, applying changes
to its schema is rightfully considered a dangerous operation. For this reason, many teams
prefer a more imperative approach where each change to the database schema is checked in
to source control and reviewed during code-review. Each such change
is called a "migration", as it migrates the database schema from the previous version to
the next. To support this kind of requirement, many popular database schema management
tools such as [Flyway](https://flywaydb.org/), [Liquibase](https://liquibase.org/) or
[golang-migrate](https://github.com/golang-migrate/migrate) support a workflow that
is commonly called "versioned migrations".

In addition to the higher level of control which is provided by versioned migrations,
applications are often deployed to multiple remote environments at once. These environments
are not controlled (or even accessible) by the development team. In such cases, declarative migrations,
which rely on a network connection to the target database and on human
approval of migrations plans in real-time, are not a feasible strategy.

With versioned migrations (sometimes called "change-based migrations"), instead of describing
the desired state ("what the database should look like"), developers describe the changes themselves
("how to reach the state"). Most of the time, this is done by creating a set of SQL files
containing the statements needed. Each of the files is assigned a unique version and a
description of the changes. Tools like the ones mentioned earlier are then able to
interpret the migration files and to apply (some of) them in the correct order to
transition to the desired database structure.

The benefit of the versioned migrations approach is that it is explicit: engineers
know _exactly_ what queries are going to be run against the database when the time
comes to execute them. Because changes are planned ahead of time, migration authors
can control precisely how to reach the desired schema. If we consider a migration as
a plan to get from state A to state B, oftentimes multiple paths exist, each with a
very different impact on the database. To demonstrate, consider an initial state which
contains a table with two columns:

```sql
CREATE TABLE users (
    id int,
    name varchar(255)
);
```
Suppose our desired state is:
```sql
CREATE TABLE users (
    id int,
    user_name varchar(255)
);
```
There are at least two ways get from the initial to the desired state:
* Drop the `name` column and create a new `user_name` column.
* Alter the name of the `name` column to `user_name`.

Depending on the context, either may be the desired outcome for the developer
planning the change. With versioned migrations, engineers have the ultimate confidence
of what change is going to happen, which may not be known ahead of time in a _declarative_
approach.

### Migration Authoring

The downside of the _versioned migration_ approach is, of course, that it puts the
burden of planning the migration on developers. This requires a certain level
of expertise that is not always available to every engineer, as we demonstrated
in our example of setting a default value in a SQLite database above.

As part of the Atlas project we advocate for a third combined approach that we call
"Versioned Migration Authoring". Versioned Migration Authoring is an attempt to combine
the simplicity and expressiveness of the declarative approach with the control and
explicitness of versioned migrations.

With versioned migration authoring, users still declare their desired state and use
the Atlas engine to plan a safe migration from the existing to the new state.
However, instead of coupling planning and execution, plans are instead written
into normal migration files which can be checked into source control, fine-tuned manually and
reviewed in regular code review processes.

### Getting started

Start by downloading the Atlas CLI:

<InstallationInstructions />

Next, define a simple Atlas schema with one table and an empty migration directory:

```hcl title="schema.hcl"
schema "test" {}

table "users" {
  schema = schema.test
  column "id" {
    type = int
  }
}
```

Let's run `atlas migrate diff` with the necessary parameters to generate a migration script for
creating our `users` table:

* `--dir` the URL to the migration directory, by default it is `file://migrations`.
* `--to` the URL of the desired state, an HCL file or a database connection.
* `--dev-url` a [URL](/concepts/url) to a [Dev Database](/concepts/dev-database) that will be used to compute the diff.

```bash
atlas migrate diff create_users \
  --dir="file://migrations" \
  --to="file://schema.hcl" \
  --dev-url="mysql://root:pass@:3306/test"
```

Observe that two files were created in the `migrations` directory:

<Tabs
defaultValue="migration_file"
values={[
{label: '20220811074144_create_users.sql', value: 'migration_file'},
{label: 'atlas.sum', value: 'sum_file'},
]}>
<TabItem value="migration_file">

By default, migration files are named with the following format `{{ now }}_{{ name }}.sql`.
If you wish to use a different file format, use the `--dir-format` option.

```sql
-- create "users" table
CREATE TABLE `users` (`id` int NOT NULL) CHARSET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
```

</TabItem>
<TabItem value="sum_file">

In addition to the migration directory, Atlas maintains a file name `atlas.sum` which is used
to ensure the integrity of the migration directory and force developers to deal with situations
where migration order or contents were modified after the fact.

```text
h1:t1fEP1rSsGf1gYrYCjsGyEyuM0cnhATlq93B7h8uXxY=
20220811074144_create_users.sql h1:liZcCBbAn/HyBTqBAEVar9fJNKPTb2Eq+rEKZeCFC9M=
```

</TabItem>
</Tabs>

### Further reading

To learn more about Versioned Migration Authoring:
* Read the [docs](/versioned/diff)
* [CLI Command Reference](/cli-reference#atlas-migrate-diff)

Have questions? Feedback? Find our team [on our Discord server](https://discord.gg/zZ6sWVg6NT).
